Using Advanced Job Object Functions(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 4 - Advanced Printing Features / Using Advanced Printing Features

Using Advanced Job Object Functions
QuickDraw GX advanced job object functions allow you to obtain specific information about a particular job object. You can use these functions to

retrieve printer driver and device information
set or retrieve a job object's reference constant
copy job objects

Obtaining Printer and Printer Driver Information for a Job
The job object contains information about the output and formatting printers. You can obtain references to these printer objects with the GXGetJobOutputPrinter and GXGetJobFormattingPrinter functions, respectively. Listing 4-1 shows how to obtain the reference to the output printer with the GXGetJobOutputPrinter function.
You can use these references to call functions to obtain additional information about the printer and its driver from the printer object's properties. Listing 4-1 also shows how to obtain the printer's name using the GXGetPrinterName function, the printer driver's name using the GXGetPrinterDriverName function, the printer's type using the GXGetPrinterType function, and the printer driver's type using the GXGetPrinterDriverType function.
For example, you could obtain this information and display it to the user in a dialog box. In this case, you need to convert the printer type and printer driver type to strings. One way you can do this is with the BlockMove function, as shown in Listing 4-1.
Listing 4-1 Obtaining the names and types of a printer and printer driver
OSErr MyShowJobPrinterInfo(MyDocumentPtr myDocument)
{
   OSErr       err;
   gxPrinter   jobPrinter;
   OSType      deviceOSType, driverOSType;
   Str255      deviceName, deviceType, driverName, driverType;
   ...
   /* 
      Get the current printer for this job. From that, get the 
      current device name, driver name, device type, and driver 
      type. 
   */
   if (err == noErr)
   {
      jobPrinter = GXGetJobOutputPrinter(myDocument->documentJob);
      
      GXGetPrinterName(jobPrinter, deviceName);
      GXGetPrinterDriverName(jobPrinter, driverName);
      deviceOSType = GXGetPrinterType(jobPrinter);
      driverOSType = GXGetPrinterDriverType(jobPrinter);

      err = GXGetJobError(myDocument->documentJob);
      if (err == noErr)
      /* 
         Since the device and driver type are OSTypes, convert
         them to the Pascal strings to display.
      */
      {
         BlockMove(&deviceOSType, &deviceType[1], (long) 
                                             (deviceType[0] = 4));
         BlockMove(&driverOSType, &driverType[1], (long) 
                                             (driverType[0] = 4));
      }
   ...
   return err;
};
Getting and Setting the Reference Constant for a Job Object
QuickDraw GX maintains a reference constant in each job object for your application's use. You can use the GXGetJobRefCon function to obtain the reference constant and use the GXSetJobRefCon function to set it. These functions allow you to associate your own data with a particular job object.
For example, Listing 4-2 shows how you can store a pointer to the document data in the reference constant of a job object for use by an override function that is called by QuickDraw GX.
Listing 4-2 Setting the job object's reference constant property
OSErr MyDoFormatDialog(MyDocumentPtr myDocument)
{
   OSErr             err;
   gxFormat          pageFormat;
   gxDialogResult    result;
   gxEditMenuRecord  editMenuRec;
   ...

   /* 
      Store the pointer to the document in the job object's 
      reference constant to access it within the GXFormatDialog 
      override.
   */
   GXSetJobRefCon(myDocument->documentJob, myDocument);

   /* Display and handle the Custom Page Setup dialog box. */
   result = GXFormatDialog(pageFormat, nil, &editMenuRec);
   ...
   return err;
}
Listing 4-3 shows the override of the GXFormatDialog function, in which the format's job object is retrieved. From the job object, the reference constant property is retrieved, allowing access to the document associated with the job object from the override function.
Listing 4-3 Getting the job object's reference constant property
OSErr MyFormatDialogOverride(gxFormat aFormat, StringPtr title, 
                              gxDialogResult *result)
{
   MyDocumentPtr  myDocument;
   gxJob          formatJob;

   /* 
      Get the current job object by calling GXGetJob. Retrieve the 
      pointer to the document, and use it to set up the dialog box
      panel.
   */
   formatJob = GXGetJob();
   myDocument = GXGetJobRefCon(formatJob);
   MySetUpPanel(aFormat, myDocument,
                                 GXGetMessageHandlerResFile());

   /* Finally, forward this message to other handlers.*/
   return Forward_GXFormatDialog(aFormat, title, result);
}
Copying Job Object Information
You can duplicate a job object using the GXCopyJob function. This function allows you to take an existing job object that references the output and formatting printers, format object, and other job-specific information, and duplicate it for use with another document. Listing 4-4 shows how to copy the job object from the source document to the destination document. References to formats are no longer valid after you change job objects because the formats are based on another job object. You must set these references to nil.
Listing 4-4 Copying job object information
OSErr MyCopyJobToDoc(MyDocumentPtr srcDocument, MyDocumentPtr 
                     destDocument)
{
   long  pg;

   /* 
      Copy the job object information. Note that this changes any
      formats that the destination job originally had (and the
      old references become invalid). 
   */
   GXCopyJob(srcDocument->documentJob, destDocument->documentJob);
   
   /* Invalidate any old format object references */
   for (pg = 1; pg <= destDocument->numPages; pg++)
      destDocument->pageFormat[pg -1] = nil;
   
   return GXGetJobError(srcDocument->documentJob);
}